tsNetSmtpFile

Type

function

Summary

Send an asynchronous upload request to a server which retrieves the data to be sent directly from a file.

Syntax

tsNetSmtpFile(<pConnectionID>, <pFile>, <pURL>, <pFrom>, <pRcpt>, <pCallback>, [<pSettings>])

Description

This function sends a callback message on completion. To save memory, it is recommended to call tsNetCloseConn when the connection is no longer needed.

Using the smtps:// scheme will initiate an SMTP SSL connection to the server. To connect using Transport Layer Security (TLS), use a URL with a format of smtp://host:port where the port number reflects the appropriate server port for TLS connections and set the "use_ssl" array setting below to true.

The callback message will be sent with four parameters: the connection identifier, the status code sent back by the server, the number of bytes transferred and the cURL result code.

The cURL result code parameter in the callback message will be 0 for successful transfers. For any errors, further information can be retrieved by calling the tsNetRetrError function.

The settings array can consist of the following elements (not all of the settings make sense for every possible transfer type):

"enable_tcp_keepalive": Set this option to true to tell tsNet to send TCP keepalive probes.

"interface": Specify the interface, IP address or host name to be used for the outgoing connection.

"keepalive_idle": When "enable_tcp_keepalive" is set to true, use this setting to specify the number of second to wait while the connection is idle before sending keepalive probes. The default is 60 seconds.

"keepalive_interval": When "enable_tcp_keepalive" is set to true, use this setting to specify the number of seconds to wait between sending keepalive probes. The default is 60 seconds.

"local_port_range": Set the number of consecutive ports above the port specified by the "local_port_start" setting to try when finding an available port for a connection.

"local_port_start": Set the local port number of the socket to be used for the connection. It is recommended to also set "local_port_range" if you use this setting.

"no_reuse": Set to true to specify that the connection to the server should be disconnected and not left open for any future connections.

"no_transfer": Set to true to connect to the server but not perform any transfer.

"password": Set to a string containing the password to be used in any authentication requests from the server.

"proxy_headers": Set to a list of headers (one per line) that should be sent to any proxy server that is being used.

"replace_lf_crlf": If this is set to true, tsNet will convert the standard LiveCode newline in the body of the e-mail with CRLF. Some SMTP servers do not recognise the standard LiveCode end-of-line character and you may experience issues sending e-mail through them unless this is enabled.

"resolve_hosts": Specify a list (one per line) of host to IP addresses to use when resolving host name for a request. Each line must be in the format of "HOSTNAME:PORT:ADDRESS".

"save_sent_headers": Set to true to specify that external should store a copy of all the headers that it sends to the server. This must be set to true to use the tsNetRetrSentHeaders function.

"ssl_ciphers": Use this setting to specify a list of SSL ciphers (separated by colons) to be used when negotiating SSL connections.

"trace": Set this option to true to tell tsNet to include all inbound and outbound data when using tsNetSetDebugCallback() rather than just header and informational data. When this option is set, a third parameter will be posted to the debug callback function specifying the type of data that is being passed to the callback function.

"try_ssl": Set this option to true to tell tsNet to try to connect via SSL. If the connection fails to establish via SSL, connect without using SSL.

"tunnel_http_proxy": Set this option to true to tell tsNet to tunnel all operations (all protocols) through the HTTP proxy.

"username": Set to a string containing the username to be used in any authentication requests from the server.

"use_ssl": Set to true to connect using Transport Layer Security (TLS) for SMTPS and FTPS (explicit) connections.

Parameters

Name	Type	Description
pConnectionID		A arbitrary user-defined label for the connection that is used when retrieving any details of the transfer.
pFile		The full path and filename that contains the e-mail message to be sent to the server. This must should the e-mail header followed by a blank line and then the body of the e-mail.
pURL		The URL formatted as 'scheme://host:port/path' and URL-encoded as outlined in RFC 3986. For SMTP functions, the scheme must be either 'smtp' or 'smtps'.
pFrom		The e-mail address of the sender to be used in the MAIL FROM command to the SMTP server. This is unrelated to the sender listed in the mail header itself which is contained within the pData parameter.
pRcpt		The e-mail addresses of the recipients to be used in the RCPT TO command to the SMTP server. This is unrelated to the recipients listed in the mail header itself which is contained within the pData parameter.
pCallback		Specify a callback message to be sent to the current object when the transfer is complete.
pSettings		An array of additional settings that control how the transfer is initiated.

Examples

local tRcpt, tResult, tSettings
put "mysmtpusername@example.com" into tSettings["username"]
put "mysmtppassword" into tSettings["password"]
-- This next line forces the connection to be TLS
put true into tSettings["use_ssl"]
put "you@example.com" & cr & "admin@example.com" into tRcpt
-- For TLS connections, the standard port is 587
put tsNetSmtpFile("1", "/path/to/email/message.eml", \
   "smtp://smtp.example.com:587", "me@example.com", \
   tRcpt, "transferComplete", tSettings) into tResult

local tRcpt, tResult, tSettings
put "mysmtpusername@example.com" into tSettings["username"]
put "mysmtppassword" into tSettings["password"]
put "you@example.com" & cr & "admin@example.com" into tRcpt
-- Using smtps:// here forces the connection to be SSL
put tsNetSmtpFile("1", "/path/to/email/message.eml", \
   "smtps://smtp.example.com", "me@example.com", \
   tRcpt, "transferComplete", tSettings) into tResult

on transferComplete pID, pResult, pBytes, pCurlCode
   local tData, tHeaders
   if pCurlCode is not 0 then
      answer tsNetRetrError(pID)
   else
      answer "Email sent successfully"
   end if
   tsNetCloseConn pID
end transferComplete

Related

command: tsNetCloseConn

function: tsNetRetrError, tsNetRetrSentHeaders

library: tsNet

Compatibility and Support

Introduced

LiveCode 8.1

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile